Description

Introduces an extensible, deployment-neutral usage reporting pipeline for OpenViking. The core defines reporter, extractor, sink, event, and context contracts; deployments can dynamically load an external sink without adding Kafka or vendor SDK dependencies to the open-source package.

The initial extractor recognizes completed search_experience and read_experience tool parts, validates that referenced URIs belong to memories/experiences/, and emits recall/injection events from the hydrated session message view.

Reporter dispatch is best-effort and lifecycle-managed: each sink call has a five-second timeout, one reporter instance is reused per server application, and optional sink close() hooks run during shutdown.

Human Involvement

• A human participated in the implementation and review loop.
• This change was implemented entirely by an AI agent.

Related Issue

N/A

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update
• Tests

Changes Made

• Add UsageReporter, UsageExtractor, UsageSink, event, and context abstractions.
• Add configurable custom sink loading for deployment-provided integrations.
• Parse completed search_experience and read_experience tool parts into recall/injection events.
• Restrict extracted usage events to valid experience-memory URIs.
• Dispatch events after session commit using the hydrated message view.
• Reuse one reporter instance per application and close external sink resources during shutdown.
• Bound sink writes and shutdown hooks with five-second timeouts; sink failures remain best-effort and do not fail session commit.
• Expose the extracted event count as usage_events_extracted in the session task result.
• Add the official ov-experience-memory skill contract and architecture documentation.
• Add unit and session integration coverage for extraction, configuration, dispatch, timeout, lifecycle, and failure isolation.

Testing

• python -m pytest tests/unit/usage_reporter tests/session/test_session_usage_reporter.py -q --no-cov - 9 passed.
• Ruff check passed for the modified Python files.
• Ruff format check passed for the modified Python files.
• git diff --check passed.

Checklist

• Code follows the project style.
• Self-review completed.
• Tests cover extractor and reporter behavior.
• Documentation describes the extension contract.
• Kafka and vendor dependencies are not imported by the OpenViking core.
• Changes remain independent from trajectory snapshots and user settings.

Screenshots

N/A

Additional Notes

• Usage reporting is disabled by default.
• Commercial and private deployments can install a separate Python package and configure its sink class through OpenViking server configuration.
• Core delivery is intentionally best-effort; retry queues and durable delivery belong to deployment-specific sinks.